home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Online / SpeakFreely / src / blowfish / blowfish.doc < prev    next >
Text File  |  2000-05-18  |  6KB  |  150 lines
  1. The Blowfish library.
  2.  
  3. Blowfish is a block cipher that operates on 64bit (8 byte) quantities.  It
  4. uses variable size key, but 128bit (16 byte) key would normally be considered
  5. good.  It can be used in all the modes that DES can be used.  This
  6. library implements the ecb, cbc, cfb64, ofb64 modes.
  7.  
  8. Blowfish is quite a bit faster that DES, and much faster than IDEA or
  9. RC2.  It is one of the faster block ciphers.
  10.  
  11. For all calls that have an 'input' and 'output' variables, they can be the
  12. same.
  13.  
  14. This library requires the inclusion of 'blowfish.h'.
  15.  
  16. All of the encryption functions take what is called an BF_KEY as an 
  17. argument.  An BF_KEY is an expanded form of the Blowfish key.
  18. For all modes of the Blowfish algorithm, the BF_KEY used for
  19. decryption is the same one that was used for encryption.
  20.  
  21. The define BF_ENCRYPT is passed to specify encryption for the functions
  22. that require an encryption/decryption flag. BF_DECRYPT is passed to
  23. specify decryption.
  24.  
  25. Please note that any of the encryption modes specified in my DES library
  26. could be used with Blowfish.  I have only implemented ecb, cbc, cfb64 and
  27. ofb64 for the following reasons.
  28. - ecb is the basic Blowfish encryption.
  29. - cbc is the normal 'chaining' form for block ciphers.
  30. - cfb64 can be used to encrypt single characters, therefore input and output
  31.   do not need to be a multiple of 8.
  32. - ofb64 is similar to cfb64 but is more like a stream cipher, not as
  33.   secure (not cipher feedback) but it does not have an encrypt/decrypt mode.
  34. - If you want triple Blowfish, thats 384 bits of key and you must be totally
  35.   obsessed with security.  Still, if you want it, it is simple enough to
  36.   copy the function from the DES library and change the des_encrypt to
  37.   BF_encrypt; an exercise left for the paranoid reader :-).
  38.  
  39. The functions are as follows:
  40.  
  41. void BF_set_key(
  42. BF_KEY *ks;
  43. int len;
  44. unsigned char *key;
  45.         BF_set_key converts an 'len' byte key into a BF_KEY.
  46.         A 'ks' is an expanded form of the 'key' which is used to
  47.         perform actual encryption.  It can be regenerated from the Blowfish key
  48.         so it only needs to be kept when encryption or decryption is about
  49.         to occur.  Don't save or pass around BF_KEY's since they
  50.         are CPU architecture dependent, 'key's are not.  Blowfish is an
  51.     interesting cipher in that it can be used with a variable length
  52.     key.  'len' is the length of 'key' to be used as the key.
  53.     A 'len' of 16 is recomended by me, but blowfish can use upto
  54.     72 bytes.  As a warning, blowfish has a very very slow set_key
  55.     function, it actually runs BF_encrypt 521 times.
  56.     
  57. void BF_encrypt(
  58. unsigned long *data,
  59. BF_KEY *key,
  60. int encrypt);
  61.     This is the Blowfish encryption function that gets called by just about
  62.     every other Blowfish routine in the library.  You should not use this
  63.     function except to implement 'modes' of Blowfish.
  64.     I say this because the
  65.     functions that call this routine do the conversion from 'char *' to
  66.     long, and this needs to be done to make sure 'non-aligned' memory
  67.     access do not occur.
  68.     Data is a pointer to 2 unsigned long's and key is the
  69.     BF_KEY to use.  Encryption or decryption is indicated by 'encrypt'.
  70.     which can have the values BF_ENCRYPT or BF_DECRYPT.
  71.  
  72. void BF_ecb_encrypt(
  73. unsigned char *in,
  74. unsigned char *out,
  75. BF_KEY *key,
  76. int encrypt);
  77.     This is the basic Electronic Code Book form of Blowfish (in DES this
  78.     mode is called Electronic Code Book so I'm going to use the term
  79.     for blowfish as well.
  80.     Input is encrypted into output using the key represented by
  81.     key.  Depending on the encrypt, encryption or
  82.     decryption occurs.  Input is 8 bytes long and output is 8 bytes.
  83.     
  84. void BF_cbc_encrypt(
  85. unsigned char *in,
  86. unsigned char *out,
  87. long length,
  88. BF_KEY *ks,
  89. unsigned char *ivec,
  90. int encrypt);
  91.     This routine implements Blowfish in Cipher Block Chaining mode.
  92.     Input, which should be a multiple of 8 bytes is encrypted
  93.     (or decrypted) to output which will also be a multiple of 8 bytes.
  94.     The number of bytes is in length (and from what I've said above,
  95.     should be a multiple of 8).  If length is not a multiple of 8, bad 
  96.     things will probably happen.  ivec is the initialisation vector.
  97.     This function updates iv after each call so that it can be passed to
  98.     the next call to BF_cbc_encrypt().
  99.     
  100. void BF_cfb64_encrypt(
  101. unsigned char *in,
  102. unsigned char *out,
  103. long length,
  104. BF_KEY *schedule,
  105. unsigned char *ivec,
  106. int *num,
  107. int encrypt);
  108.     This is one of the more useful functions in this Blowfish library, it
  109.     implements CFB mode of Blowfish with 64bit feedback.
  110.     This allows you to encrypt an arbitrary number of bytes,
  111.     you do not require 8 byte padding.  Each call to this
  112.     routine will encrypt the input bytes to output and then update ivec
  113.     and num.  Num contains 'how far' we are though ivec.
  114.     'Encrypt' is used to indicate encryption or decryption.
  115.     CFB64 mode operates by using the cipher to generate a stream
  116.     of bytes which is used to encrypt the plain text.
  117.     The cipher text is then encrypted to generate the next 64 bits to
  118.     be xored (incrementally) with the next 64 bits of plain
  119.     text.  As can be seen from this, to encrypt or decrypt,
  120.     the same 'cipher stream' needs to be generated but the way the next
  121.     block of data is gathered for encryption is different for
  122.     encryption and decryption.
  123.     
  124. void BF_ofb64_encrypt(
  125. unsigned char *in,
  126. unsigned char *out,
  127. long length,
  128. BF_KEY *schedule,
  129. unsigned char *ivec,
  130. int *num);
  131.     This functions implements OFB mode of Blowfish with 64bit feedback.
  132.     This allows you to encrypt an arbitrary number of bytes,
  133.     you do not require 8 byte padding.  Each call to this
  134.     routine will encrypt the input bytes to output and then update ivec
  135.     and num.  Num contains 'how far' we are though ivec.
  136.     This is in effect a stream cipher, there is no encryption or
  137.     decryption mode.
  138.     
  139. For reading passwords, I suggest using des_read_pw_string() from my DES library.
  140. To generate a password from a text string, I suggest using MD5 (or MD2) to
  141. produce a 16 byte message digest that can then be passed directly to
  142. BF_set_key().
  143.  
  144. =====
  145. For more information about the specific Blowfish modes in this library
  146. (ecb, cbc, cfb and ofb), read the section entitled 'Modes of DES' from the
  147. documentation on my DES library.  What is said about DES is directly
  148. applicable for Blowfish.
  149.  
  150.